[ DOCUMENTATION ]

Memory Crystal Docs

Current product and integration reference for the Memory Crystal plugin, hosted API, and MCP server.

Release Notes

Latest plugin release: v0.6.1 (March 27, 2026).

  • Dynamic per-session channelScope override — agents can now switch channel scope at session start without changing plugin config
  • Per-call channel parameter on all MCP tools — pass channel on individual tool calls for fine-grained memory isolation
  • peekRateLimit utility and /api/mcp/rate-limit-check endpoint — check remaining rate limit budget before making calls

Full history lives on /releases.

Getting Started

  1. Install the OpenClaw plugin with the hosted installer.
  2. Approve the browser device-auth flow or pass an existing API key.
  3. Let the installer wire the plugin and restart OpenClaw.
  4. Use the same account with the hosted MCP endpoint or local MCP server if you need tool access outside OpenClaw.
curl -fsSL https://memorycrystal.ai/crystal | bash

Update an existing OpenClaw install:

curl -fsSL https://memorycrystal.ai/crystal/update | bash

Hosted MCP endpoint:

https://api.memorycrystal.ai/mcp

Run the local MCP server from this repo:

cd mcp-server && npm run start

Memory Architecture

Memory Crystal currently runs as a two-layer memory system: short-term message storage for live conversation continuity and long-term durable memories for recall across sessions, tools, and machines.

  • Capture: user and assistant turns are logged to short-term memory, then distilled into long-term memories.
  • Compaction: the OpenClaw plugin owns compaction and can replace older raw turns with local summaries.
  • Snapshots: compaction and trace flows persist source conversation snapshots so summaries stay auditable.
  • Prompt-aware local summary injection: local summaries are searched for relevance and injected when enabled by plugin config.
  • Knowledge graph: graph enrichment and graph-query tools add ownership, dependency, and connection context.
  • Reflection + consolidation: background jobs promote low-salience sensory memories, distill decisions/lessons, and keep long-term memory usable as volume grows.

Stores: sensory, episodic, semantic, procedural, prospective. Categories: decision, lesson, person, rule, event, fact, goal, workflow, conversation.

Tool Reference

These are the current crystal_* tools exposed by the repo today. The OpenClaw plugin also registers legacy compatibility tools memory_search and memory_get, but they are not listed here because they are not crystal_* tools.

Shared Memory Tools

crystal_remember
Save a durable memory with store/category metadata.
crystal_recall
Search long-term memories by semantic relevance.
crystal_recent
Fetch recent short-term conversation messages.
crystal_search_messages
Search short-term messages for exact prior wording and nearby matches.
crystal_what_do_i_know
Summarize what Memory Crystal knows about a topic before starting work.
crystal_why_did_we
Decision archaeology over prior choices and rationale.
crystal_checkpoint
Create or list checkpoints at milestones.
crystal_preflight
Surface rules, lessons, and decisions before risky actions.
crystal_stats
Return health and store statistics.
crystal_wake
Generate a wake briefing with goals, decisions, and recent context.
crystal_trace
Trace a saved memory back to the source conversation snapshot.
crystal_edit
Edit an existing memory by id — update title, content, store, category, or tags.
crystal_forget
Archive a memory by id. Plugin registrations still show a dashboard fallback until all clients pick up the deployed endpoint.

Graph Query Tools

crystal_who_owns
Query graph-backed ownership and responsibility relationships.
crystal_explain_connection
Explain how two entities are connected in the knowledge graph.
crystal_dependency_chain
Traverse dependencies for a project, goal, or system.

OpenClaw Local Session Tools

crystal_grep
Search local in-session messages and summaries inside the OpenClaw plugin's local store.
crystal_describe
Inspect a local summary node by id.
crystal_expand
Expand a local summary node back toward underlying messages and children.

OpenClaw Integration

The current plugin entry point is plugin/index.js, with openclaw.plugin.json as the active manifest. Legacy compatibility files handler.js and openclaw-hook.json remain in the install payload for older environments.

  • Recall layer: before-agent-start and before-tool-call hooks surface wake briefings, recall results, and preflight warnings.
  • Capture layer: message-received, llm-output, and fallback hooks persist turns, trigger memory extraction, and write media assets.
  • Context engine: the plugin owns compaction, local summaries, and relevance-based summary injection.
  • REST transport: plugin calls currently go through /api/mcp/* endpoints, while the standalone MCP server exposes the shared tool set for external clients.

Pricing & Limits

Tier
Price
Memories
Messages
Retention
Channels
FREE
$0/mo
500
500
7 days
3
PRO
$29/mo
25,000
25,000
30 days
Unlimited
ULTRA
$79/mo
Unlimited
Unlimited
90 days
Unlimited
ENTERPRISE
Custom
Custom
Custom
Custom
Custom
  • Pro and Ultra start with a 7-day free trial in the current pricing flow.
  • Starter is a legacy alias that maps to Pro limits in code.
  • Enterprise is handled as custom pricing and custom limits.

FAQ

Do I need OpenClaw to use Memory Crystal?

No. OpenClaw is the deepest integration, but the hosted endpoint and local MCP server expose the tool surface to other MCP clients.

What shipped in the latest plugin version?

v0.6.1 added the current lossless-memory work, including traceable snapshots and prompt-aware local summary injection.

How do I recover the source of a memory?

Use crystal_trace. It follows a saved memory back to the source conversation snapshot when one exists.

How are limits enforced?

Long-term memory counts, short-term message counts, channel counts, and short-term retention are all derived from shared/tierLimits.ts.

Memory Crystal — Persistent Memory for Claude Code, Codex & AI Agents